2025年8月21日中文

深入探讨 JavaScript 装饰器，探索其语法、元数据编程用例、最佳实践及其对代码可维护性的影响。包含实践示例和未来展望。

JavaScript 装饰器：实现元数据编程

JavaScript 装饰器是一项强大的功能，它允许您以声明式和可重用的方式添加元数据并修改类、方法、属性和参数的行为。它是 ECMAScript 标准流程中的一个第三阶段提案，并与 TypeScript 广泛使用，后者有其自己（略有不同）的实现。本文将全面概述 JavaScript 装饰器，重点关注其在元数据编程中的作用，并通过实践示例说明其用法。

什么是 JavaScript 装饰器？

装饰器是一种设计模式，用于在不改变对象结构的情况下增强或修改其功能。在 JavaScript 中，装饰器是可以附加到类、方法、访问器、属性或参数的特殊声明。它们使用 @ 符号后跟一个函数，该函数将在被装饰的元素定义时执行。

可以将装饰器看作是函数，它接受被装饰的元素作为输入，并返回该元素的修改版本，或基于它执行某些副作用。这提供了一种清晰而优雅的方式来添加功能，而无需直接修改原始的类或函数。

关键概念：

装饰器函数： @ 符号后面的函数。它接收有关被装饰元素的信息并可以对其进行修改。
被装饰的元素： 被装饰的类、方法、访问器、属性或参数。
元数据： 描述数据的数据。装饰器通常用于将元数据与代码元素关联起来。

语法与结构

装饰器的基本语法如下：

@decorator
class MyClass {
  // 类成员
}

这里，@decorator 是装饰器函数，MyClass 是被装饰的类。装饰器函数在类定义时被调用，并且可以访问和修改类的定义。

装饰器也可以接受参数，这些参数会传递给装饰器函数本身：

@loggable(true, "Custom Message")
class MyClass {
  // 类成员
}

在这种情况下，loggable 是一个装饰器工厂函数，它接受参数并返回实际的装饰器函数。这使得装饰器更加灵活和可配置。

装饰器的类型

根据装饰的对象不同，有不同类型的装饰器：

类装饰器： 应用于类。
方法装饰器： 应用于类中的方法。
访问器装饰器： 应用于 getter 和 setter 访问器。
属性装饰器： 应用于类属性。
参数装饰器： 应用于方法的参数。

类装饰器

类装饰器用于修改或增强类的行为。它们接收类构造函数作为参数，并可以返回一个新的构造函数来替换原始构造函数。这使您能够添加日志记录、依赖注入或状态管理等功能。

示例：

function loggable(constructor: Function) {
  console.log("类 " + constructor.name + " 已创建。");
}

@loggable
class User {
  name: string;

  constructor(name: string) {
    this.name = name;
  }
}

const user = new User("Alice"); // 输出：类 User 已创建。

在此示例中，loggable 装饰器在每次创建 User 类的新实例时都会向控制台记录一条消息。这对于调试或监控非常有用。

方法装饰器

方法装饰器用于修改类中方法的行为。它们接收以下参数：

target：类的原型。
propertyKey：方法的名称。
descriptor：方法的属性描述符。

描述符允许您访问和修改方法的行为，例如用附加逻辑包装它或完全重新定义它。

示例：

function logMethod(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;

  descriptor.value = function (...args: any[]) {
    console.log(`调用方法 ${propertyKey}，参数为：${args}`);
    const result = originalMethod.apply(this, args);
    console.log(`方法 ${propertyKey} 返回：${result}`);
    return result;
  };
  return descriptor;
}

class Calculator {
  @logMethod
  add(a: number, b: number): number {
    return a + b;
  }
}

const calculator = new Calculator();
const sum = calculator.add(5, 3); // 输出方法调用和返回值的日志

在此示例中，logMethod 装饰器记录了方法的参数和返回值。这对于调试和性能监控非常有用。

访问器装饰器

访问器装饰器与方法装饰器类似，但应用于 getter 和 setter 访问器。它们接收与方法装饰器相同的参数，并允许您修改访问器的行为。

示例：

function validate(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalSet = descriptor.set;

  descriptor.set = function (value: any) {
    if (value < 0) {
      throw new Error("值必须为非负数。");
    }
    originalSet.call(this, value);
  };
}

class Temperature {
  private _celsius: number;

  constructor(celsius: number) {
    this._celsius = celsius;
  }

  @validate
  set celsius(value: number) {
    this._celsius = value;
  }

  get celsius(): number {
    return this._celsius;
  }
}

const temperature = new Temperature(25);
temperature.celsius = 30; // 有效
// temperature.celsius = -10; // 抛出错误

在此示例中，validate 装饰器确保温度值为非负数。这对于强制执行数据完整性非常有用。

属性装饰器

属性装饰器用于修改类属性的行为。它们接收以下参数：

target：类的原型（对于实例属性）或类构造函数（对于静态属性）。
propertyKey：属性的名称。

属性装饰器可用于定义元数据或修改属性的描述符。

示例：

function readonly(target: any, propertyKey: string) {
  Object.defineProperty(target, propertyKey, {
    writable: false,
  });
}

class Configuration {
  @readonly
  apiUrl: string = "https://api.example.com";
}

const config = new Configuration();
// config.apiUrl = "https://newapi.example.com"; // 在严格模式下抛出错误

在此示例中，readonly 装饰器使 apiUrl 属性变为只读，防止其在初始化后被修改。这对于定义不可变的配置值非常有用。

参数装饰器

参数装饰器用于修改方法参数的行为。它们接收以下参数：

target：类的原型（对于实例方法）或类构造函数（对于静态方法）。
propertyKey：方法的名称。
parameterIndex：参数在方法参数列表中的索引。

参数装饰器不如其他类型的装饰器常用，但它们可用于验证输入参数或注入依赖项。

示例：

function required(target: any, propertyKey: string, parameterIndex: number) {
  const existingRequiredParameters: number[] = Reflect.getOwnMetadata(propertyKey, target, "required") || [];
  existingRequiredParameters.push(parameterIndex);
  Reflect.defineMetadata(propertyKey, existingRequiredParameters, target, "required");
}

function validateMethod(target: any, propertyName: string, descriptor: PropertyDescriptor) {
  let method = descriptor.value!;

  descriptor.value = function () {
    let requiredParameters: number[] = Reflect.getOwnMetadata(propertyName, target, "required");
    if (requiredParameters) {
      for (let parameterIndex of requiredParameters) {
        if (arguments[parameterIndex] === null || arguments[parameterIndex] === undefined) {
          throw new Error(`缺少索引为 ${parameterIndex} 的必需参数`);
        }
      }
    }

    return method.apply(this, arguments);
  };
}


class ArticleService {
  create(
    @required title: string,
    @required content: string
  ): void {
    console.log(`正在创建文章，标题：${title}，内容：${content}`);
  }
}

const service = new ArticleService();
// service.create("My Article", null); // 抛出错误
service.create("My Article", "Article Content"); // 有效

在此示例中，required 装饰器将参数标记为必需，而 validateMethod 装饰器确保这些参数不为 null 或 undefined。这对于强制执行方法输入验证非常有用。

使用装饰器进行元数据编程

装饰器最强大的用例之一是元数据编程。元数据是关于数据的数据。在编程的上下文中，它是描述代码结构、行为和目的的数据。装饰器提供了一种清晰、声明式的方式，将元数据与类、方法、属性和参数关联起来。

The Reflect Metadata API

Reflect Metadata API 是一个标准 API，允许您存储和检索与对象关联的元数据。它提供以下函数：

Reflect.defineMetadata(key, value, target, propertyKey)：为对象的特定属性定义元数据。
Reflect.getMetadata(key, target, propertyKey)：检索对象的特定属性的元数据。
Reflect.hasMetadata(key, target, propertyKey)：检查对象的特定属性是否存在元数据。
Reflect.deleteMetadata(key, target, propertyKey)：删除对象的特定属性的元数据。

您可以将这些函数与装饰器结合使用，以将元数据与您的代码元素关联起来。

示例：定义和检索元数据

import 'reflect-metadata';

const logKey = "log";

function log(message: string) {
  return function (target: any, key: string, descriptor: PropertyDescriptor) {
    Reflect.defineMetadata(logKey, message, target, key);

    const originalMethod = descriptor.value;
    descriptor.value = function (...args: any[]) {
      console.log(Reflect.getMetadata(logKey, target, key));
      const result = originalMethod.apply(this, args);
      return result;
    }

    return descriptor;
  }
}

class Example {
  @log("正在执行方法")
  myMethod(arg: string): string {
    return `方法已调用，参数为 ${arg}`;
  }
}

const example = new Example();
example.myMethod("Hello"); // 输出：正在执行方法, 方法已调用，参数为 Hello

在此示例中，log 装饰器使用 Reflect Metadata API 将一条日志消息与 myMethod 方法关联起来。当方法被调用时，装饰器会检索该消息并将其记录到控制台。

元数据编程的用例

使用装饰器进行元数据编程有许多实际应用，包括：

序列化和反序列化： 使用元数据注释属性，以控制它们如何序列化为 JSON 或其他格式，或从这些格式反序列化。这在处理来自外部 API 或数据库的数据时非常有用，尤其是在需要在不同平台间进行数据转换的分布式系统中（例如，在不同区域标准之间转换日期格式）。想象一个处理国际收货地址的电子商务平台，您可以使用元数据为每个国家指定正确的地址格式和验证规则。
依赖注入： 使用元数据来识别需要注入到类中的依赖项。这简化了依赖项的管理并促进了松散耦合。考虑一个服务相互依赖的微服务架构。装饰器和元数据可以促进基于配置的服务客户端的动态注入，从而更容易实现扩展和容错。
验证： 将验证规则定义为元数据，并使用装饰器自动验证数据。这确保了数据完整性并减少了样板代码。例如，一个全球金融应用程序需要遵守各种区域性金融法规。元数据可以根据用户的位置定义货币格式、税收计算和交易限额的验证规则，以确保遵守当地法律。
路由和中间件： 使用元数据为 Web 应用程序定义路由和中间件。这简化了应用程序的配置，并使其更易于维护。一个全球分布的内容分发网络（CDN）可以使用元数据根据内容类型和用户位置定义缓存策略和路由规则，从而优化性能并减少全球用户的延迟。
授权和认证： 将角色、权限和认证要求与方法和类关联，从而促进声明式安全策略。想象一个在不同部门和地点拥有员工的跨国公司。装饰器可以根据用户的角色、部门和位置定义访问控制规则，确保只有授权人员才能访问敏感数据和功能。

最佳实践

在使用 JavaScript 装饰器时，请考虑以下最佳实践：

保持装饰器简单： 装饰器应重点突出，执行单一、明确定义的任务。避免在装饰器中使用复杂的逻辑，以保持可读性和可维护性。
使用装饰器工厂： 使用装饰器工厂以允许可配置的装饰器。这使您的装饰器更加灵活和可重用。
避免副作用： 装饰器应主要专注于修改被装饰的元素或与其关联元数据。避免在装饰器中执行复杂的副作用，这可能会使您的代码更难理解和调试。
使用 TypeScript： TypeScript 为装饰器提供了出色的支持，包括类型检查和智能感知（IntelliSense）。使用 TypeScript 可以帮助您及早发现错误并改善开发体验。
为您的装饰器编写文档： 清晰地记录您的装饰器，解释其用途和使用方法。这使其他开发人员更容易理解和正确使用您的装饰器。
考虑性能： 虽然装饰器功能强大，但它们也可能影响性能。请注意装饰器的性能影响，尤其是在性能关键的应用程序中。

使用装饰器实现国际化的示例

装饰器可以通过将特定于区域设置的数据和行为与代码组件关联，来辅助国际化（i18n）和本地化（l10n）：

示例：本地化日期格式

import 'reflect-metadata';

interface DateFormatOptions {
  locale: string;
  options?: Intl.DateTimeFormatOptions;
}

const dateFormatKey = 'dateFormat';

function formatDate(options: DateFormatOptions) {
  return function(target: any, propertyKey: string) {
    Reflect.defineMetadata(dateFormatKey, options, target, propertyKey);
  };
}

class Event {
  @formatDate({ locale: 'fr-FR', options: { year: 'numeric', month: 'long', day: 'numeric' } })
  startDate: Date;

  constructor(startDate: Date) {
    this.startDate = startDate;
  }

  getFormattedStartDate(): string {
    const options: DateFormatOptions = Reflect.getMetadata(dateFormatKey, Object.getPrototypeOf(this), 'startDate');
    return this.startDate.toLocaleDateString(options.locale, options.options);
  }
}

const event = new Event(new Date());
console.log(event.getFormattedStartDate()); // 以法语格式输出日期

示例：根据用户位置格式化货币

import 'reflect-metadata';

interface CurrencyFormatOptions {
  locale: string;
  currency: string;
}

const currencyFormatKey = 'currencyFormat';

function formatCurrency(options: CurrencyFormatOptions) {
  return function(target: any, propertyKey: string) {
    Reflect.defineMetadata(currencyFormatKey, options, target, propertyKey);
  };
}

class Product {
  @formatCurrency({ locale: 'de-DE', currency: 'EUR' })
  price: number;

  constructor(price: number) {
    this.price = price;
  }

  getFormattedPrice(): string {
    const options: CurrencyFormatOptions = Reflect.getMetadata(currencyFormatKey, Object.getPrototypeOf(this), 'price');
    return this.price.toLocaleString(options.locale, { style: 'currency', currency: options.currency });
  }
}

const product = new Product(99.99);
console.log(product.getFormattedPrice()); // 以德国欧元格式输出价格

未来展望

JavaScript 装饰器是一个不断发展的功能，其标准仍在制定中。一些未来的考虑包括：

标准化： ECMAScript 的装饰器标准仍在进行中。随着标准的发展，装饰器的语法和行为可能会发生变化。
性能优化： 随着装饰器被更广泛地使用，将需要进行性能优化，以确保它们不会对应用程序性能产生负面影响。
工具支持： 改进对装饰器的工具支持，例如 IDE 集成和调试工具，将使开发人员更容易有效地使用装饰器。

结论

JavaScript 装饰器是实现元数据编程和增强代码行为的强大工具。通过使用装饰器，您可以以一种清晰、声明式和可重用的方式添加功能。这有助于编写更易于维护、测试和扩展的代码。了解不同类型的装饰器以及如何有效地使用它们对于现代 JavaScript 开发至关重要。装饰器，特别是与 Reflect Metadata API 结合使用时，开启了一系列可能性，从依赖注入和验证到序列化和路由，使您的代码更具表现力且更易于管理。